Skip to content

feat(governance): add agent intent governance (ADR 0014)#26

Merged
fedeoliv merged 1 commit into
mainfrom
feat/agent-intent-governance
Jun 8, 2026
Merged

feat(governance): add agent intent governance (ADR 0014)#26
fedeoliv merged 1 commit into
mainfrom
feat/agent-intent-governance

Conversation

@fedeoliv

@fedeoliv fedeoliv commented May 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

This PR introduces additional engineering discipline inspired by The Architecture of Intent to close three structural gaps:

  • Framework agents had no explicit behavioral envelope; coordinator agents now declare Behavioral Constraints (rules tools cannot enforce) and Composition (cross-component invariants).
  • Consumer specs describing AI capabilities had no canonical fragment for operational cost commitments; the feature template now carries a gated AI Cost Posture block (model tier, latency budget, prompt stability, per-call cost ceiling, cost-incident escalation), opted into via Describes AI capability: yes metadata in the Executive Summary.
  • The failure diagnosis surface on the debugging-recovery skill had no taxonomy mapping a failure to the upstream artifact that owns the fix. Now it ships a three-category upstream-artifact principle - failure (spec), failure (validation), failure (agent).

Spec evolution log added to feature and migration spec templates with the three failure trigger values. Docs site gains a new concept page (AI Capability Specs), two new sections in Spec Amendment, and five glossary entries.

ADR 0014 records the decision, options considered, and the AoI constructs deliberately not adopted (custom frontmatter scalars, Reversibility tier, Pattern A/B/C/D/E taxonomy, seven-category failure taxonomy, standalone authoring handbook, signal metrics, phase rename). AoI attribution added to ACKNOWLEDGMENTS under Articles and Blog Posts.

CHANGELOG entry filed under [Unreleased]; manifest versions unchanged (release bump deferred to release commit).

@fedeoliv
feat(governance): add agent intent governance (ADR 0014)
1a0f6bc 
Selectively adopts vocabulary and discipline from 'The Architecture of
Intent' by Marcel Aldecoa to close three structural gaps:

- Framework agents had no explicit behavioral envelope; coordinator
  agents now declare ## Behavioral Constraints (rules tools cannot
  enforce) and ## Composition (cross-component invariants).
- Consumer specs describing AI capabilities had no canonical fragment
  for operational cost commitments; the feature template now carries a
  gated ## AI Cost Posture block (model tier, latency budget, prompt
  stability, per-call cost ceiling, cost-incident escalation), opted
  into via 'Describes AI capability: yes' in the Executive Summary.
- The failure-diagnosis surface had no taxonomy mapping a failure to
  the upstream artifact that owns the fix; debugging-recovery now
  ships a three-category upstream-artifact principle (failure (spec),
  failure (validation), failure (agent)).

Spec evolution log added to feature and migration spec templates with
the three failure trigger values. Docs site gains a new concept page
(AI Capability Specs), two new sections in Spec Amendment, and five
glossary entries. ADR 0014 records the decision, options considered,
and the AoI constructs deliberately not adopted (custom frontmatter
scalars, Reversibility tier, Pattern A/B/C/D/E taxonomy, seven-category
failure taxonomy, standalone authoring handbook, signal metrics,
phase rename). AoI attribution added to ACKNOWLEDGMENTS under Articles
and Blog Posts.

CHANGELOG entry filed under [Unreleased]; manifest versions unchanged
(release bump deferred to release commit).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@fedeoliv fedeoliv requested a review from marcelaldecoa May 14, 2026 19:17
@marcelaldecoa

marcelaldecoa commented May 28, 2026

Copy link
Copy Markdown
Member

PR #26 Review — AoI Selective Adoption into DevSquad Copilot

Reviewer: Marcel Aldecoa (Author, The Architecture of Intent)
PR: #26
Author: @fedeoliv + Copilot
Date: 2026-05-28

Summary

This PR selectively adopts three constructs from The Architecture of Intent (AoI) to close structural gaps in DevSquad Copilot's agent instructions, spec templates, and debugging-recovery surface. An ADR (0014) documents both what was adopted and what was deliberately rejected.

Verdict: ✅ APPROVE

The adoption is disciplined, structurally sound, and honest about scope. The three additions solve real gaps without over-engineering the framework.

What Was Adopted

1. Behavioral Constraints + Composition Declaration (Agent Instructions)

Aspect Detail
What changed Coordinator agents now declare ## Behavioral Constraints (rules tools cannot enforce) and ## Composition (cross-component invariants)
AoI source Part 1 Ch.5 — Composing Archetypes; §4 Composition Declaration sub-block of the canonical spec template
Alignment quality 🟢 Excellent — directly instantiates the "composition is a first-class design surface" principle
Value delivered Makes the behavioral envelope explicit; prevents the "composition by accident" anti-pattern AoI identifies

2. AI Cost Posture (Feature Spec Template)

Aspect Detail
What changed Feature template gains a gated ## AI Cost Posture block with five fields: model tier, latency budget, prompt stability, per-call cost ceiling, cost-incident escalation
AoI source §4 Cost Posture sub-block; Part 6 Ch.2 Cost and Latency Engineering; four signal metrics (cost-per-correct-outcome)
Alignment quality 🟢 Excellent — near 1:1 structural match with the five Cost Posture bullets in AoI's canonical template
Value delivered Gives DevSquad specs a production-readiness commitment that was previously implicit; prevents the "pilot works, rollout doesn't pencil" failure shape
Design choice Gated behind Describes AI capability: yes in the Executive Summary — smart scoping; not every feature spec needs this

3. Three-Category Failure Taxonomy (Debugging-Recovery)

Aspect Detail
What changed Debugging-recovery gains an upstream-artifact principle: failure (spec) / failure (validation) / failure (agent)
AoI source Part 0 Ch.5 — Failure Modes and How to Diagnose Them (seven-category fix-locus taxonomy)
Alignment quality 🟡 Good — justified simplification
Value delivered Routes failures to the artifact that owns the fix; prevents the "blame the model" attribution instinct
Simplification rationale Collapses AoI's seven categories into three upstream-artifact buckets. This is correct for DevSquad's context: DevSquad agents don't perceive physical environments (no Cat 7), and the finer distinctions (Cat 2 Tool vs. Cat 3 Composition vs. Cat 4 Oversight) can be collapsed since DevSquad's debugging surface doesn't need that granularity to route a fix. ADR 0014 makes this explicit.

4. Spec Evolution Log (Templates)

Aspect Detail
What changed Feature and migration spec templates gain a spec evolution log with three failure trigger values
AoI source Part 5 — Closed-loop discipline (amendments flow back to the artifact each Cat names)
Alignment quality 🟢 Excellent — directly implements the closed-loop: failure → categorize → amend upstream artifact

5. Supporting Changes

  • Concept page: "AI Capability Specs" on docs site — good discoverability
  • Spec Amendment additions: two new sections contextualizing the evolution log
  • Glossary: five new entries grounding the vocabulary
  • ACKNOWLEDGMENTS: AoI attributed under Articles and Blog Posts
  • CHANGELOG: filed under [Unreleased]; no version bump yet (correct — bump belongs to release commit)

What Was Deliberately Not Adopted (ADR 0014)

AoI Construct Reason for Rejection Assessment
Custom frontmatter scalars DevSquad already has its own frontmatter convention ✅ Correct
Reversibility tier (R1–R4) DevSquad's undo model is structural (git + spec versioning), not tiered ✅ Correct
Pattern A/B/C/D/E composition taxonomy Too granular for DevSquad's composition surface; the principle matters, the taxonomy doesn't ✅ Correct
Seven-category failure taxonomy Three categories sufficient for DevSquad's debugging surface ✅ Correct
Standalone authoring handbook DevSquad's docs site already serves this role ✅ Correct
Signal metrics DevSquad measures differently (backlog health, velocity, quality gate pass rate) ✅ Correct
Phase rename DevSquad's eight-phase names are established; renaming would break muscle memory ✅ Correct

Assessment: Every rejection is well-reasoned. The PR demonstrates the AoI Adoption Playbook's first principle: tight-focus — adopt what solves your acute problem, leave the rest.

Conductor Agent Refactoring

Beyond the AoI adoptions, the PR cleans up the conductor agent:

  • Removed the inline sub-agent routing table (agents are surfaced via description: at invocation time — no need to duplicate)
  • Streamlined routing decisions to a focused bullet list
  • Tightened behavioral language: "relay sub-agent questions to the user verbatim" → explicit no-filter policy
  • Removed "run mutating terminal commands" from "You do NOT" — correct Orchestrator discipline

This maps cleanly to AoI's Orchestrator archetype: coordinates, delegates, sequences; does not generate output that belongs to a sub-agent's scope.

Suggestions (Non-Blocking)

1. Consider linking failure categories to the evolution log

The three failure triggers (failure (spec) / failure (validation) / failure (agent)) in the spec evolution log could reference which section of the spec is most likely to need amendment for each category. AoI's discipline: "failure → categorize → amend the specific artifact that owns the fix." A one-line hint per trigger type would close the loop tighter.

2. Cost Posture: consider naming the downstream metric

AoI's Cost Posture sub-block explicitly names cost-per-correct-outcome as the downstream metric the upstream commitment serves. If DevSquad has (or plans) a cost efficiency metric, naming it in the template text would close the spec↔measurement loop.

3. Future consideration: Cat 7 awareness

If DevSquad ever gains computer-use or browser-use agent capabilities, the three-category taxonomy will need a fourth bucket (perceptual failure). The ADR could note this as an explicit future-trigger for re-evaluation.

Final Assessment

Criterion Rating
Structural soundness ⭐⭐⭐⭐⭐
Honest accounting (what adopted / what rejected) ⭐⭐⭐⭐⭐
Alignment with AoI principles ⭐⭐⭐⭐⭐
Practical value to DevSquad users ⭐⭐⭐⭐
Documentation quality ⭐⭐⭐⭐⭐

This is how selective framework adoption should look: identify the structural gaps, adopt the constructs that close them, document what you evaluated and rejected, and attribute the source. Well done.

@fedeoliv fedeoliv merged commit d8db35c into main Jun 8, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@marcelaldecoa marcelaldecoa marcelaldecoa approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@fedeoliv @marcelaldecoa